package com.gobang.service;

import com.gobang.domain.enums.GameStatus;
import com.gobang.domain.enums.PlayerColor;

/**
 * 游戏引擎接口
 * 使用状态机模式管理游戏流程和状态转换
 * 
 * @author System
 * @since 1.0.0
 */
public interface GameEngine {

    /**
     * 初始化游戏状态
     *
     * @param roomId 房间ID
     * @param blackPlayerId 黑方玩家ID
     * @param whitePlayerId 白方玩家ID
     * @return 是否初始化成功
     */
    boolean initializeGame(String roomId, Long blackPlayerId, Long whitePlayerId);

    /**
     * 开始游戏
     * 状态从WAITING转换为PLAYING
     *
     * @param roomId 房间ID
     * @return 是否开始成功
     */
    boolean startGame(String roomId);

    /**
     * 处理游戏状态转换
     *
     * @param roomId 房间ID
     * @param fromStatus 源状态
     * @param toStatus 目标状态
     * @return 是否转换成功
     */
    boolean transitionGameState(String roomId, GameStatus fromStatus, GameStatus toStatus);

    /**
     * 切换玩家回合
     * 在黑方和白方之间切换
     *
     * @param roomId 房间ID
     * @return 切换后的玩家颜色
     */
    PlayerColor switchTurn(String roomId);

    /**
     * 获取当前回合玩家
     *
     * @param roomId 房间ID
     * @return 当前回合玩家颜色
     */
    PlayerColor getCurrentTurn(String roomId);

    /**
     * 检查是否轮到指定玩家
     *
     * @param roomId 房间ID
     * @param userId 用户ID
     * @return 是否轮到该玩家
     */
    boolean isPlayerTurn(String roomId, Long userId);

    /**
     * 获取玩家颜色
     *
     * @param roomId 房间ID
     * @param userId 用户ID
     * @return 玩家颜色
     */
    PlayerColor getPlayerColor(String roomId, Long userId);

    /**
     * 结束游戏
     * 状态转换为FINISHED
     *
     * @param roomId 房间ID
     * @param winnerId 获胜者ID
     * @param reason 结束原因
     * @return 是否结束成功
     */
    boolean endGame(String roomId, Long winnerId, String reason);

    /**
     * 取消游戏
     * 状态转换为CANCELLED
     *
     * @param roomId 房间ID
     * @param reason 取消原因
     * @return 是否取消成功
     */
    boolean cancelGame(String roomId, String reason);

    /**
     * 获取游戏状态
     *
     * @param roomId 房间ID
     * @return 游戏状态
     */
    GameStatus getGameStatus(String roomId);

    /**
     * 验证状态转换是否合法
     *
     * @param fromStatus 源状态
     * @param toStatus 目标状态
     * @return 是否合法
     */
    boolean isValidStateTransition(GameStatus fromStatus, GameStatus toStatus);
} 